package ucd.csi.comp30220.fall2011.oteop.flight;

import ucd.csi.comp30220.fall2011.oteop.collision.Collision;
import ucd.csi.comp30220.fall2011.oteop.navigation.Position;

/**
 * Flights are the main currency of the system. 
 * 
 * @author David Harrison
 */
public interface Flight {
    
    public static final String JMDNS_SUB_TYPE = "flight";
    
    /** @return the flight information */
    public FlightInfo getInfo() throws FlightException;

    /** @return where we are is right now */
    public Position getPosition() throws FlightException;

    /** @return course we are on right now (degrees) */
    public double getCourse() throws FlightException;

    /** @return how fast are we going right now (knots) */
    public int getSpeed() throws FlightException;

    /** @return how high we are right now (feet) */
    public int getAltitude() throws FlightException;

    /** @return <code>true</code> if we happen to be thundering down the runway just now */
    public boolean takingOff() throws FlightException;
    
    /** @return are we helping ourself to lunch and a nice Chianti? */
    public boolean inLevelFlight() throws FlightException; 

    /** @return are we about to crash, sorry, land? */
    public boolean onFinalApproach() throws FlightException; 

    /** @return <code>true</code> if all safe and sound */
    public boolean hasLanded() throws FlightException;
    
    /** 
     * Let's get this thing in the air! Ordinarily only called by an Airport.
     * 
     * @throws AlredyStartedException if the flight left without us
     * @throws FailedToStartException if we misplaced the keys
     **/
    public void start() throws AlreadyStartedException, FailedToStartException;
    
    /**
     * Without a supplied route, the flight will make it's way to it's destination
     * on it's own. AirTraffic will probably want to meddle with this in the
     * interest of avoiding total anarchy in the skies.
     * 
     * @param waypoints an array of positions to fly to one by one
     * @throws FlightException
     */
    public void setRoute(Position[] waypoints) throws FlightException;
    
    /**
     * @param course
     * @throws FlightException
     */
    public void setCourse(double course) throws FlightException;
    
    /**
     * @param atlitude
     * @throws FlightException
     */
    public void setAltitude(int altitude) throws FlightException;
    
    /**
     * In extreme circumstances, someone may want to to let us know that big metal
     * thing we can see zooming towards us may well get closer than is normally 
     * regarded as comfortable.
     * 
     * @param collision where, when and with whom we are expected to collide
     * @throws FlightException
     */
    public void collisionDetected(Collision collision) throws FlightException;
}    